C Index File Functions (CIFF) Version 1.00 Copyright (C) 1992 by Tini Software Group(TSG) All rights reserved NOTICE ------------------------ Tini Software Group MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Tini Software Group shall not be liable for errors contained herein or for incidental consequential damages in connection with the furnishing, performance, or use of this material. This document contains proprietary information which is protected by copyright. All rights reserved. The information contained in this document is subject to change without notice. Contents ------------------------ CIFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Valid operations . . . . . . . . . . . . . . . . . . . . . . . 3 ciff_open. . . . . . . . . . . . . . . . . . . . . . . . . . . 4 ciff_close . . . . . . . . . . . . . . . . . . . . . . . . . . 5 ciff_read. . . . . . . . . . . . . . . . . . . . . . . . . . . 6 ciff_curr. . . . . . . . . . . . . . . . . . . . . . . . . . . 7 ciff_first . . . . . . . . . . . . . . . . . . . . . . . . . . 8 ciff_last. . . . . . . . . . . . . . . . . . . . . . . . . . . 9 ciff_prev. . . . . . . . . . . . . . . . . . . . . . . . . . . 10 ciff_next. . . . . . . . . . . . . . . . . . . . . . . . . . . 11 ciff_gteq. . . . . . . . . . . . . . . . . . . . . . . . . . . 12 ciff_gt. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 ciff_lteq. . . . . . . . . . . . . . . . . . . . . . . . . . . 14 ciff_lt. . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 ciff_altkey. . . . . . . . . . . . . . . . . . . . . . . . . . 16 ciff_write . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ciff_delete. . . . . . . . . . . . . . . . . . . . . . . . . . 18 ciff_update. . . . . . . . . . . . . . . . . . . . . . . . . . 19 ciff_error . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Page 3 CIFF was designed to handle indexed records from within 'C'. CIFF creates two files IndexFileName.IDX and IndexFileName.DAT. Records within CIFF may be accessed or retrieved through one or more keys. The keys and records can be variable length. There are two types of keys: 1: primary key (only one is allowed) 2: alternate keys (up to 3) The value of the primary key distinguishes it from other primary keys therefor this value must be unique from other primary keys. Like primary keys alternate key values must be unique form other alternate keys of that type (i.e. alternate key1 can not be identical to any other alternate key1, however, it can be identical to an alternate key2 or alternate key3). Alternate keys are used to look up records and CAN NOT be used to add, delete or update records. Once a key is added it is not possible to change the value of the key, unless, the record is deleted and re-entered. The keys must be of type char and no larger then 50 bytes. Records can be of any type and up to 32767 bytes. When adding records to the index file it will increase the speed of CIFF functions if the record size passed to ciff_write is large enough to hold an updated record. Dos allows 20 files to be opened at once, 5 of these files are reserved by DOS for system use, therefor the maximum number of index files opened at once is 7 (2 files are opened for each index file). If CIFF is a test version the number of records in the index file is limited to 20. CIFF Operation CIFF Function Call Open an index file ciff_open Close an index file ciff_close Read a record ciff_read Read current record ciff_curr Read the first record ciff_first Read the last record ciff_last Read next record ciff_next Read previous record ciff_prev Read greater than or equal to ciff_gteq Read greater than ciff_gt Read less than or equal to ciff_lteq Read less than ciff_lt Add an alternate key ciff_altkey Write a record ciff_write Update a record ciff_update Delete a record ciff_delete Print a CIFF error message ciff_error Page 4 Function ciff_open Syntax: int ciff_open(char *file_name, char *mode); Parameters: file_name char * Name of index file to open (up to 8 characters). mode char * Access to the index file. Description: Open the index file Index file name. Mode used in calls to ciff_open is one of the following values: r - read only rw - read/write If the index file does not exists and ciff_open was called with mode equal to "r" ciff_open will return an error, else if ciff_open was called using "rw" ciff_open will create the index file. If the mode is "r" records CAN NOT be added, updated or deleted. On successful completion, CIFF_OPEN returns a non-negative integer (file handle). Return values: -1: Error creating index file -2: Error creating data file -3: Error opening index file -4: Error opening data file >0: File handle Number Example main() { int i, handle; handle = ciff_open("CLIENTS", "rw"); if(handle < 1) { ciff_error(handle); exit(1); } i = ciff_close(handle); if(i) { ciff_error(i); exit(1); } } Page 5 Function ciff_close Syntax: int ciff_close(int handle); Parameters: handle int file handle associated with the index file to close. Description: Close the index file associated with handle. If handle is -1 ciff_close will close all index files opened. Return values: 0: Success !0: Error Example main() { int i, handle; handle = ciff_open("CLIENTS","rw"); if(handle < 1) { ciff_error(handle); exit(1); } i = ciff_close(handle); if(i) { ciff_error(i); exit(1); } } Page 6 Function ciff_read Syntax: int ciff_read(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key to read. record void * Pointer to record data. key_number int Key to use. Description: Return the record that corresponds to the key. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -5: Record not found Example main() { char record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if(handle < 1) { ciff_error(handle); exit(1); } i = ciff_read(handle, "John Doe", record, 0); if (i) ciff_error(i); else printf("John Doe's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 7 Function ciff_curr Syntax: int ciff_curr(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key returned. record void * Pointer to record data. key_number int Key to use. Description: Read the current record. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -5: Record not found Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_curr(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s",key, record); i = ciff_close(handle); if (!i) { ciff_error(i); exit(1); } } Page 8 Function ciff_first Syntax: int ciff_first(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key returned. record void * Pointer to record data. key_number int Key to use. Description: Read the first record. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -9: Empty index file Example main() { char key[50]; record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_first(handle, key, record, 0) if (i) ciff_error(i); else printf("%s's address is %s",key, record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 9 Function ciff_last Syntax: int ciff_last(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key returned. record void * Pointer to record data. key_number int Key to use. Description: Read the last record. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -9: Empty index file Example main() { char key[50]; record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_last(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s",key, record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 10 Function ciff_next Syntax: int ciff_next(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key returned. record void * Pointer to record data. key_number int Key to use. Description: Read the next record. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -7: End of index file Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_next(handle, key,record, 0); if (i) ciff_error(i); else printf("%s's address is %s",key, record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 11 Function ciff_prev Syntax: int ciff_prev(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * Pointer to key returned. record void * Pointer to record data. key_number int Key to use. Description: Read the previous record. Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -8: Beginning of index file Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i =ciff_prev(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s",key, record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 12 Function ciff_gteq Syntax: int ciff_gteq(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * when called is pointer to key to find on return is pointer to new key. record void * Pointer to record data. key_number int Key to use. Description: Get a record greater than or equal to key( key MUST be large enough to hold the returning key). Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -7: Last record reached Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i =ciff_gteq(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 13 Function ciff_gt Syntax: int ciff_gt(int handle, char *key, void *record, int key_number); Parameters: handle int Handle associated with the index file. key char * when called is pointer to key to find on return is pointer to new key value. record void * Pointer to record data. key_number int Key to use. Description: Get a record greater than key (key MUST be large enough to hold the returning key). Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -7: End of index file Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_gt(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 14 Function ciff_lteq Syntax: int ciff_lteq(int handle, char *key, void *record, int key number); Parameters: handle int Handle associated with the index file. key char * when called pointer to key to find on return pointer to new key value. record void * Pointer to record returned. key_number int Key to use. Description: Get a record less than or equal to key (key MUST be large enough to hold the returning key). Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -8: First record reached Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_lteq(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 15 Function ciff_lt Syntax: int ciff_lt(int handle, char *key, void *record, int key number); Parameters: handle int Handle associated with the index file. key char * when called pointer to key to find on return pointer to new key value. record void * Pointer to record returned. key_number int Key to use. Description: Get a record less than key (key MUST be large enough to hold the returning key). Key number is the key to use (0-Primary key, 1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -8: First record reached Example main() { char key[50], record[200]; int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_lt(handle, key, record, 0); if (i) ciff_error(i); else printf("%s's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 16 Function ciff_altkey Syntax: int ciff_altkey(int handle, char *pri_key, char *alt_key, int key_number); Parameters: handle int Handle associated with the index file. pri_key char * Pointer to primary key. alt_key char * Pointer to alternate key. key_number int Key to use. Description: Add alternate key to the index file. Key number is the key to use (1-Alternate key1, 2-Alternate key2, 3-Alternate key3). Return values: 0: Success -10: Duplicate alt key -11: Primary key not found -12: Error inserting alternate key Example main() { int handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_altkey(handle, "John Doe","187487754", 1); if (i) ciff_error(i); else printf("%s's address is %s", record); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 17 Function ciff_write Syntax: int ciff_write(int handle, char *key, void *record, int rec_len); Parameters: handle int Handle associated with the index file. key char * Pointer to key to write. record void * Pointer to record returned. rec_len int Record length. Description: Write the record. Key is the primary key to the record, records CAN NOT be added with alternate keys. Return values: 0: Success -6: Duplicate key Example main() { int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_write(handle, "John Doe", "1024 Gilroy Street, Scranton, PA 18505", 38); if (i) ciff_error(i); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 18 Function ciff_update Syntax: int ciff_update(int file handle, char *key, void *record, int rec_len); Parameters: handle int Handle associated with the index file. key char * Pointer to key to update. record void * Pointer to record returned. rec_len int Record length. Description: Update the record. Key must be the primary key to the record, records CAN NOT be updated with alternate keys. Return values: 0: Success -5: Record not found Example main() { int handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_update(handle, "John Doe", "1050 Main Street, Scranton, PA 18505", 36); if (i) ciff_error(i); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 19 Function ciff_delete Syntax: int ciff_delete(int handle, char *key); Parameters: handle int Handle associated with the index file. key char * Pointer to key to delete. Description: Delete the record. Key is the primary key to the record, records CAN NOT be deleted with alternate keys. Return values: 0: Success -5: Record not found Example main() { int i, handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_delete(handle, "John Doe"); if (i) ciff_error(i); i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } Page 20 Function ciff_error Syntax: void ciff_error(int err_number); Parameters: err_number int Error number to print message for. Description: Print the error message associated with error number returned from a CIFF function. Errors: -1: CIFF_ERR001 - Error creating index file -2: CIFF_ERR002 - Error creating data file -3: CIFF_ERR003 - Error opening index file -4: CIFF_ERR004 - Error opening data file -5: CIFF_ERR005 - Record not found -6: CIFF_ERR006 - Duplicate record -7: CIFF_ERR008 - First record reached -8: CIFF_ERR007 - Last record reached -9: CIFF_ERR009 - Empty index file -10: CIFF_ERR010 - Primary key not found -11: CIFF_ERR011 - Error inserting alternate key -14: CIFF_ERR014 - Max index files opened -15: CIFF_ERR015 - File handle not in use -17: CIFF_ERR017 - Invalid key -19: CIFF_ERR019 - Access denied -22: CIFF_ERR022 - Test version - Maximum records exceeded ?: CIFF_ERRUKN - Unknown error Example main() { int handle; handle = ciff_open("CLIENTS", "rw"); if (handle < 1) { ciff_error(handle); exit(1); } i = ciff_close(handle); if (i) { ciff_error(i); exit(1); } } ----------------end-of-author's-documentation--------------- Software Library Information: This disk copy provided as a service of Public (software) Library We are not the authors of this program, nor are we associated with the author in any way other than as a distributor of the program in accordance with the author's terms of distribution. Please direct shareware payments and specific questions about this program to the author of the program, whose name appears elsewhere in this documentation. If you have trouble getting in touch with the author, we will do whatever we can to help you with your questions. All programs have been tested and do run. To report problems, please use the form that is in the file PROBLEM.DOC on many of our disks or in other written for- mat with screen printouts, if possible. PsL cannot debug pro- programs over the telephone, though we can answer questions. Disks in the PsL are updated monthly, so if you did not get this disk directly from the PsL, you should be aware that the files in this set may no longer be the current versions. Also, if you got this disk from another vendor and are having prob- lems, be aware that some files may have become corrupted or lost by that vendor. Get a current, working disk from PsL. For a copy of the latest monthly software library newsletter and a list of the 3,000+ disks in the library, call or write Public (software) Library P.O.Box 35705 - F Houston, TX 77235-5705 Orders only: 1-800-2424-PSL MC/Visa/AmEx/Discover Outside of U.S. or in Texas or for general information, Call 1-713-524-6394 PsL also has an outstanding catalog for the Macintosh.